<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>libwebsockets: Built-in service loop entry</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="libwebsockets.org-logo.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">libwebsockets
   </div>
   <div id="projectbrief">Lightweight C library for HTML5 websockets</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li class="current"><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__service.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">Built-in service loop entry</div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gaf95bd0c663d6516a0c80047d9b1167a8"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#gaf95bd0c663d6516a0c80047d9b1167a8">lws_service</a> (struct lws_context *context, int timeout_ms)</td></tr>
<tr class="separator:gaf95bd0c663d6516a0c80047d9b1167a8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga9b3cc4473fd8848e5bbee7f310712939"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#ga9b3cc4473fd8848e5bbee7f310712939">lws_service_tsi</a> (struct lws_context *context, int timeout_ms, int tsi)</td></tr>
<tr class="separator:ga9b3cc4473fd8848e5bbee7f310712939"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga29c246707997ab7a466aa709aecd2d7b"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#ga29c246707997ab7a466aa709aecd2d7b">lws_cancel_service_pt</a> (struct lws *wsi)</td></tr>
<tr class="separator:ga29c246707997ab7a466aa709aecd2d7b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga53e3d0801dfda7960a7249dd559e68a2"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#ga53e3d0801dfda7960a7249dd559e68a2">lws_cancel_service</a> (struct lws_context *context)</td></tr>
<tr class="separator:ga53e3d0801dfda7960a7249dd559e68a2"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gad82efa5466d14a9f05aa06416375b28d"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#gad82efa5466d14a9f05aa06416375b28d">lws_service_fd</a> (struct lws_context *context, struct <a class="el" href="structlws__pollfd.html">lws_pollfd</a> *<a class="el" href="structpollfd.html">pollfd</a>)</td></tr>
<tr class="separator:gad82efa5466d14a9f05aa06416375b28d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaebf426eda371ba23642fc11d8e0ace6b"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#gaebf426eda371ba23642fc11d8e0ace6b">lws_service_fd_tsi</a> (struct lws_context *context, struct <a class="el" href="structlws__pollfd.html">lws_pollfd</a> *<a class="el" href="structpollfd.html">pollfd</a>, int tsi)</td></tr>
<tr class="separator:gaebf426eda371ba23642fc11d8e0ace6b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4fd9d714434ca499e2b3f7dbba86f241"><td class="memItemLeft" align="right" valign="top">LWS_VISIBLE LWS_EXTERN int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#ga4fd9d714434ca499e2b3f7dbba86f241">lws_service_adjust_timeout</a> (struct lws_context *context, int timeout_ms, int tsi)</td></tr>
<tr class="separator:ga4fd9d714434ca499e2b3f7dbba86f241"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gab1ff2c19455268fa0d5b617d8057fbfc"><td class="memItemLeft" align="right" valign="top">LWS_EXTERN LWS_VISIBLE int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__service.html#gab1ff2c19455268fa0d5b617d8057fbfc">lws_plat_service_tsi</a> (struct lws_context *context, int timeout_ms, int tsi)</td></tr>
<tr class="separator:gab1ff2c19455268fa0d5b617d8057fbfc"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>lws_client_http_body_pending() - control if client connection neeeds to send body</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">wsi</td><td>client connection </td></tr>
    <tr><td class="paramname">something_left_to_send</td><td>nonzero if need to send more body, 0 (default) if nothing more to send</td></tr>
  </table>
  </dd>
</dl>
<p>If you will send payload data with your HTTP client connection, eg, for POST, when you set the related http headers in LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call this API with something_left_to_send nonzero, and call lws_callback_on_writable(wsi);</p>
<p>After sending the headers, lws will call your callback with LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable. You can send the next part of the http body payload, calling lws_callback_on_writable(wsi); if there is more to come, or lws_client_http_body_pending(wsi, 0); to let lws know the last part is sent and the connection can move on.</p>
<h2>Built-in service loop entry</h2>
<p>If you're not using libev / libuv, these apis are needed to enter the poll() wait in lws and service any connections with pending events. </p>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="ga53e3d0801dfda7960a7249dd559e68a2"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_VISIBLE LWS_EXTERN void lws_cancel_service </td>
          <td>(</td>
          <td class="paramtype">struct lws_context *&#160;</td>
          <td class="paramname"><em>context</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#ga53e3d0801dfda7960a7249dd559e68a2">lws_cancel_service()</a> - Cancel wait for new pending socket activity </p><dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">context</td><td>Websocket context <pre class="fragment"> This function let a call to lws_service() waiting for a timeout
 immediately return.

 What it basically does is provide a fake event that will be swallowed,
 so the wait in poll() is ended.  That's useful because poll() doesn't
 attend to changes in POLLIN/OUT/ERR until it re-enters the wait.</pre> </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a class="anchor" id="ga29c246707997ab7a466aa709aecd2d7b"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_VISIBLE LWS_EXTERN void lws_cancel_service_pt </td>
          <td>(</td>
          <td class="paramtype">struct lws *&#160;</td>
          <td class="paramname"><em>wsi</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#ga29c246707997ab7a466aa709aecd2d7b">lws_cancel_service_pt()</a> - Cancel servicing of pending socket activity on one thread </p><dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">wsi</td><td>Cancel service on the thread this wsi is serviced by <pre class="fragment"> This function lets a call to lws_service() waiting for a timeout
 immediately return.

 It works by creating a phony event and then swallowing it silently.

 The reason it may be needed is when waiting in poll(), changes to
 the event masks are ignored by the OS until poll() is reentered.  This
 lets you halt the poll() wait and make the reentry happen immediately
 instead of having the wait out the rest of the poll timeout.</pre> </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a class="anchor" id="gab1ff2c19455268fa0d5b617d8057fbfc"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_EXTERN LWS_VISIBLE int lws_plat_service_tsi </td>
          <td>(</td>
          <td class="paramtype">struct lws_context *&#160;</td>
          <td class="paramname"><em>context</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>timeout_ms</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>tsi</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#gab1ff2c19455268fa0d5b617d8057fbfc">lws_plat_service_tsi()</a> - Lowlevel platform-specific service api </p><dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">context</td><td>Websocket context </td></tr>
    <tr><td class="paramname">timeout_ms</td><td>The original poll timeout value. You can just set this to 1 if you don't really have a poll timeout. </td></tr>
    <tr><td class="paramname">tsi</td><td>thread service index</td></tr>
  </table>
  </dd>
</dl>
<p>For default poll() and libuv/ev, lws takes care of using this for you. and you can ignore it.</p>
<p>But for external poll() integration, you need access to this api to service connections that need to be serviced but have no pending network activity.</p>
<p>See <a class="el" href="group__service.html#ga4fd9d714434ca499e2b3f7dbba86f241">lws_service_adjust_timeout()</a> for more info. </p>

</div>
</div>
<a class="anchor" id="gaf95bd0c663d6516a0c80047d9b1167a8"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_VISIBLE LWS_EXTERN int lws_service </td>
          <td>(</td>
          <td class="paramtype">struct lws_context *&#160;</td>
          <td class="paramname"><em>context</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>timeout_ms</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#gaf95bd0c663d6516a0c80047d9b1167a8">lws_service()</a> - Service any pending websocket activity </p><dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">context</td><td>Websocket context </td></tr>
    <tr><td class="paramname">timeout_ms</td><td>Timeout for poll; 0 means return immediately if nothing needed service otherwise block and service immediately, returning after the timeout if nothing needed service.</td></tr>
  </table>
  </dd>
</dl>
<p>This function deals with any pending websocket traffic, for three kinds of event. It handles these events on both server and client types of connection the same.</p>
<p>1) Accept new connections to our context's server</p>
<p>2) Call the receive callback for incoming frame data received by server or client connections.</p>
<p>You need to call this service function periodically to all the above functions to happen; if your application is single-threaded you can just call it in your main event loop.</p>
<p>Alternatively you can fork a new process that asynchronously handles calling this service in a loop. In that case you are happy if this call blocks your thread until it needs to take care of something and would call it with a large nonzero timeout. Your loop then takes no CPU while there is nothing happening.</p>
<p>If you are calling it in a single-threaded app, you don't want it to wait around blocking other things in your loop from happening, so you would call it with a timeout_ms of 0, so it returns immediately if nothing is pending, or as soon as it services whatever was pending. </p>

</div>
</div>
<a class="anchor" id="ga4fd9d714434ca499e2b3f7dbba86f241"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_VISIBLE LWS_EXTERN int lws_service_adjust_timeout </td>
          <td>(</td>
          <td class="paramtype">struct lws_context *&#160;</td>
          <td class="paramname"><em>context</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>timeout_ms</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>tsi</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#ga4fd9d714434ca499e2b3f7dbba86f241">lws_service_adjust_timeout()</a> - Check for any connection needing forced service </p><dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">context</td><td>Websocket context </td></tr>
    <tr><td class="paramname">timeout_ms</td><td>The original poll timeout value. You can just set this to 1 if you don't really have a poll timeout. </td></tr>
    <tr><td class="paramname">tsi</td><td>thread service index</td></tr>
  </table>
  </dd>
</dl>
<p>Under some conditions connections may need service even though there is no pending network action on them, this is "forced service". For default poll() and libuv / libev, the library takes care of calling this and dealing with it for you. But for external poll() integration, you need access to the apis.</p>
<p>If anybody needs "forced service", returned timeout is zero. In that case, you can call <a class="el" href="group__service.html#gab1ff2c19455268fa0d5b617d8057fbfc">lws_plat_service_tsi()</a> with a timeout of -1 to only service guys who need forced service. </p>

</div>
</div>
<a class="anchor" id="gad82efa5466d14a9f05aa06416375b28d"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_VISIBLE LWS_EXTERN int lws_service_fd </td>
          <td>(</td>
          <td class="paramtype">struct lws_context *&#160;</td>
          <td class="paramname"><em>context</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">struct <a class="el" href="structlws__pollfd.html">lws_pollfd</a> *&#160;</td>
          <td class="paramname"><em>pollfd</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#gad82efa5466d14a9f05aa06416375b28d">lws_service_fd()</a> - Service polled socket with something waiting </p><dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">context</td><td>Websocket context </td></tr>
    <tr><td class="paramname">pollfd</td><td>The pollfd entry describing the socket fd and which events happened, or NULL to tell lws to do only timeout servicing.</td></tr>
  </table>
  </dd>
</dl>
<p>This function takes a pollfd that has POLLIN or POLLOUT activity and services it according to the state of the associated struct lws.</p>
<p>The one call deals with all "service" that might happen on a socket including listen accepts, http files as well as websocket protocol.</p>
<p>If a pollfd says it has something, you can just pass it to <a class="el" href="group__service.html#gad82efa5466d14a9f05aa06416375b28d">lws_service_fd()</a> whether it is a socket handled by lws or not. If it sees it is a lws socket, the traffic will be handled and pollfd-&gt;revents will be zeroed now.</p>
<p>If the socket is foreign to lws, it leaves revents alone. So you can see if you should service yourself by checking the pollfd revents after letting lws try to service it.</p>
<p>You should also call this with pollfd = NULL to just allow the once-per-second global timeout checks; if less than a second since the last check it returns immediately then. </p>

</div>
</div>
<a class="anchor" id="gaebf426eda371ba23642fc11d8e0ace6b"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_VISIBLE LWS_EXTERN int lws_service_fd_tsi </td>
          <td>(</td>
          <td class="paramtype">struct lws_context *&#160;</td>
          <td class="paramname"><em>context</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">struct <a class="el" href="structlws__pollfd.html">lws_pollfd</a> *&#160;</td>
          <td class="paramname"><em>pollfd</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>tsi</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#gaebf426eda371ba23642fc11d8e0ace6b">lws_service_fd_tsi()</a> - Service polled socket in specific service thread </p><dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">context</td><td>Websocket context </td></tr>
    <tr><td class="paramname">pollfd</td><td>The pollfd entry describing the socket fd and which events happened. </td></tr>
    <tr><td class="paramname">tsi</td><td>thread service index</td></tr>
  </table>
  </dd>
</dl>
<p>Same as <a class="el" href="group__service.html#gad82efa5466d14a9f05aa06416375b28d">lws_service_fd()</a> but used with multiple service threads </p>

</div>
</div>
<a class="anchor" id="ga9b3cc4473fd8848e5bbee7f310712939"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">LWS_VISIBLE LWS_EXTERN int lws_service_tsi </td>
          <td>(</td>
          <td class="paramtype">struct lws_context *&#160;</td>
          <td class="paramname"><em>context</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>timeout_ms</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>tsi</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code>#include &lt;<a class="el" href="libwebsockets_8h.html">lib/libwebsockets.h</a>&gt;</code></p>
<p><a class="el" href="group__service.html#gaf95bd0c663d6516a0c80047d9b1167a8">lws_service()</a> - Service any pending websocket activity</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">context</td><td>Websocket context </td></tr>
    <tr><td class="paramname">timeout_ms</td><td>Timeout for poll; 0 means return immediately if nothing needed service otherwise block and service immediately, returning after the timeout if nothing needed service.</td></tr>
  </table>
  </dd>
</dl>
<p>Same as <a class="el" href="group__service.html#gaf95bd0c663d6516a0c80047d9b1167a8">lws_service()</a>, but for a specific thread service index. Only needed if you are spawning multiple service threads. </p>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.11 </li>
  </ul>
</div>
</body>
</html>
